Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 7 - Finder Interface Reference / Finder Interface Functions

Finding Directories /

FindFolder

CHANGED WITH MAC OS 8

Gets the location information used to gain access to the system-related directories.

pascal OSErr FindFolder (
                     short vRefNum,
                     OSType folderType,
                     Boolean createFolder,
                     short *foundVRefNum,
                     long *foundDirID);

vRefNum

The volume reference number (or the constant kOnSystemDisk for the startup disk) of the volume on which you want to locate a directory; see "Folder Type Constants".

folderType

A four-character folder type, or a constant that represents the type, for the folder you want to find; see "Folder Type Constants". Use the kTrashFolderType constant to locate the current user's Trash directory for a given volume--even one located on a file server. On a file server, you can use the kWhereToEmptyTrashFolderType constant to locate the parent directory of all logged-on users' Trash subdirectories.

createFolder

Pass the constant kCreateFolder to create a directory if it does not already exist; otherwise, pass the constant kDontCreateFolder. Directories inside the System Folder are created only if the System Folder directory exists. The FindFolder function will not create a System Folder directory even if you specify the kCreateFolder constant in the createFolder parameter. Passing kCreateFolder will also not create a parent folder; if the parent of the target folder does not already exist, attempting to create the target will fail.

foundVRefNum

On output, a pointer to the volume reference number for the volume containing the directory you specify in the folderType parameter.

foundDirID

On output, a pointer to the directory ID number for the directory you specify in the folderType parameter.

function result

A result code; see "Result Codes". The result code fnfErr indicates that the type has not been found in the 'fld#' resource, or the disk doesn't have System Folder support, or the disk does not have desktop database support for Desktop Folder--in all cases, the folder has not been found. The result code dupFNErr indicates that a file has been found instead of a folder.

DISCUSSION

The FindFolder function can now be used to locate folders registered using the AddFolderDescriptor function.

For the folder type on the particular volume (specified, respectively, in the folderType and vRefNum parameters), the FindFolder function returns the directory's volume reference number through the foundVRefNum parameter and its directory ID through the foundDirID parameter. Each folder that can be found with FindFolder is described in a folder descriptor structure; see "The Folder Descriptor Structure".

Those folders you're most likely to want to access are Preferences, Temporary Items, and Trash. For example, you might wish to check for the existence of a user's configuration file in Preferences, create a temporary file in Temporary Items, or, if your application runs out of disk storage when trying to save a file, check how much disk storage is taken by items in the Trash directory and report this to the user.

The specified folder used for a given volume might be located on a different volume in future versions of system software; therefore, do not assume the volume that you specify in vRefNum and the volume returned through foundVRefNum will be the same.

SPECIAL CONSIDERATIONS

Prior to Mac OS 8, the Finder identified the subdirectories of the System Folder, and their folder types, in a resource of type 'fld#' located in the System file. While some backwards compatibility support for 'fld#' remains, it has been superseded by the 'nfd#' resource. As with 'fld#', you should not modify or rely on the contents of the 'nfd#' resource in the System file. Instead, use only the FindFolder function to find the appropriate folders, and use the functions AddFolderDescriptor and RemoveFolderDescriptor to modify folder descriptors.

WHEN MAC OS 8 IS NOT AVAILABLE

The FindFolder function cannot be used to locate folders registered using the AddFolderDescriptor function. Also, prior to Mac OS 8, the Finder identified the subdirectories of the System Folder, and their folder types, in a resource of type 'fld#' located in the System file. Do not modify or rely on the contents of the 'fld#' resource in the System file; use only the FindFolder function to find the appropriate directories.